Перейти к основному содержимому
Версия: 2.0

Описание API

Общие сведения об API v2: URL, аутентификация, эндпоинты

Общие изменения в API v2​

По сравнению с версией v1, в новых методах произошли следующие изменения:

  1. Формат времени: Все временные метки (updated_at, last_categorized_at) переведены в строковый формат ISO 8601 с точностью до микросекунд. Например: "2024-07-22T10:30:00.123456Z"
  2. Структура ответа: Ответ теперь представляет собой прямой JSON-массив объектов, без верхнеуровневого ключа-обертки. Это упрощает обработку данных на стороне клиента

Базовый URL​

Для вызова методов API необходимо использовать базовый URL https://api.data.rt-solar.ru/api/v2.

Аутентификация​

Аутентификация производится с помощью JWT-токена. Токен должен быть передан в заголовке Authorization по схеме Bearer.

Получение токена​

Токен выдаётся по запросу в поддержку Solar TI Feeds (support.tic@rt-solar.ru). В письме укажите ваш проект, необходимые фиды и срок его действия. Токен приходит в ответном письме.

Срок жизни токена​

По умолчанию JWT-токен имеет ограниченный срок жизни, задаваемый при его получении. По истечении срока необходимо запросить новый токен через поддержку.

Список эндпоинтов​

Управление фидами​

Права доступа к фидам для пользователя

Пользователю возвращаются только разрешенные для него политикой доступа фиды.
Доступ к фидам для пользователя устанавливается на уровне родительских и/или дочерних фидов.
Логика формирования ответа:

  • Если разрешен родительский фид, то при запросе по родительскому фиду возвращаются индикаторы из родительского и разрешенных дочерних фидов
  • Если родительский фид не разрешен, но разрешены его дочерние, то в ответе вернутся индикаторы только из разрешенных дочерних фидов
Пример 1: Запрос разрешенного родительского фида

Запрос: /api/v2/feeds/4rays_pulse (фид разрешен).
Результат: Возвращаются все индикаторы с фидом 4rays_pulse + индикаторы из разрешенных дочерних фидов.
Объяснение: Так как родительский фид разрешен, возвращаются индикаторы разрешенных дочерних фидов.

Пример 2: Запрос запрещенного родительского фида

Запрос: /api/v2/feeds/generic (фид generic запрещен, но разрешны несколько дочерних).
Результат: Возвращаются только индикаторы из разрешенных дочерних фидов.
Объяснение: Родительский фид запрещен, поэтому возвращаются только индикаторы из явно разрешенных дочерних фидов.

Пример 3: Запрос без параметра

Запрос: /api/v2/feeds (вызов без параметров).
Результат: Возвращаются все индикаторы из доступных пользователю фидов.
Объяснение: При вызове метода без параметров вернутся все индикаторы из доступных пользователю фидов.

Управление правилами​

Solar TI Feeds API v2 предоставляет возможность получения категорий доменов как по открытым, так и по хешированным FQDN (полным доменным именам) через REST API.

Поддерживаются типы:
  • WAF
  • IDS (например, Suricata)
  • YARA
  • SIGMA

Для каждого типа существуют коллекции (например, suricata_trend, et_open_clear).
Правила распространяются в виде файлов с контролем версий (по хешу).

Управление доменами​

Solar TI Feeds предоставляет доступ к коллекциям правил для детектирования атак.

Алгоритм проверки хешей

Для использования баз знаний Solar TI Feeds при определении категорий доменов необходимо придерживаться описанного ниже алгоритма в связи с использованием хешированных значений FQDN.
1. Подготовка доменного имени:

  • Подготовьте сравниваемое значение домена, полученное из внешнего источника. Рекомендуется убрать лишние уровни вложенности доменного имени, так как проверка имён выше третьего уровня с большой вероятностью даст отрицательный результат. Большинство доменов базы имеет 2-3 уровень
  • Если исходное значение — URL, оставьте только доменное имя без указания схемы и пути (например, из https://sub.example.com/path извлекается sub.example.com)
  • Приведите полученное доменное имя к кодировке UTF-8

2. Вычисление SHA-256 хеша:

  • Вычислите хеш-сумму полученного результата с использованием хеш-функции SHA-256
  • Для вычисления SHA-256 хеша используйте стандартные криптографические библиотеки вашего языка программирования или инструмента разработки

3. Поиск в базе Solar TI Feeds:

  • Выполните поиск полученного значения хеша по данным Solar TI Feeds на совпадение с полем hash_fqdn
  • Если точного совпадения нет, уберите поддомены и повторно вычислите хеш полученного родительского домена (например, для sub.example.com проверить example.com) и повторить поиск в базе данных

Примечание: Категории поддоменов и родительских доменов могут различаться.

4. Интерпретация результата:

  • Совпадение хешей означает, что домен присутствует в базе и относится к указанным категориям
  • Отсутствие совпадения означает, что домен не классифицирован в базе данных Solar TI Feeds

Структура ответа при ошибке​

При ошибках 401, 404 и 500 структура ответа будет содержать код ошибки (status), сообщение об ошибке (message) и опционально описание (description).

Пример ответа с кодами 401, 404 и 500​

{
  "description": "string",
  "message": "string",
  "status": 401
}

При возвращении ошибки 400 в ответе перечисляются все параметры, не прошедшие валидацию:

Пример ответа с кодом 400​

{
  "description": "Ошибка валидации входных параметров",
  "errors": {
    "updated_at": "Filed value does not match required ISO 8601 format with microseconds"
  },
  "message": "ErrValidationError",
  "status": 400
}